\documentstyle{article}
\begin{document}

\title{VisualMaker}
\author{David L\"ubbren\\Leopoldstr. 3\\76133 Karlsruhe\\Germany}

\maketitle

\begin{abstract} 
{\bf VisualMaker} is a Tool for automatically generating a {\tt DMakefile} for {\bf DiCe}'s
Make utility. Features include a fully graphical user interface, automatic
scanning of source files for headerfile dependancies and handling of
precompiled header dependancies. Supports all {\bf DiCe} compiler options
and uses symbol names and variable assignments in the output file, grouping
all files with the same options together. Takes into account the environment
variable {\tt DCCOPTS}.\\  Version 1.0. Requires AmigaDOS2.0.  Binary only.
\end{abstract}                 


\newpage
\tableofcontents
\newpage

\section{Legal Stuff}

      VisualMaker V1.0 \copyright David L\"ubbren.
      {\bf VisualMaker} is SHAREWARE, and may be distributed in a non-
      commercial 
      way (you may copy, spread, and use it but don't make money out of it).

      If you like {\bf VisualMaker} and regularly use it, I would appreciate being 
      sent a {\bf \$10} contribution to the above address.  Contributors will 
      receive the complete copyrighted source in C. 

       Suggestions, comments and criticisms are also welcome at the above 
       address. If any problems are encountered, please report them! 


\centerline{Disclaimer}

      DAVID L\"UBBREN MAKES NO WARRANTIES EITHER EXPRESSED OR IMPLIED, WITH 
      RESPECT TO THIS SOFTWARE, ITS QUALITY, PERFORMANCE OR FITNESS FOR ANY 
      PARTICULAR PURPOSE.  THIS SOFTWARE IS PROVIDED "AS IS." THE ENTIRE 
      RISK AS TO QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH THE USER.  
      IN NO EVENT WILL DAVID L�BBREN BE LIABLE FOR DIRECT, INDIRECT, 
      INCIDENTAL OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT IN THE 
      SOFTWARE. 




\section{Introduction}

      {\bf VisualMaker} is a 'MakeFile' generator for the {\bf DiCe} compiler package.
      The program is fully controlled through an Intuition interface and 
      allows compiler options to be set for individual files with just a
      couple of mouse clicks. All compiler options are supported. The 
      generated {\tt DMakefile} includes the basic object $\rightarrow$ source, 
      executable $\rightarrow$ object dependancies as well as dependancies 
      for all included headers,
      precompiled headers and errorfile deletion prior to a new run. The 
      output format is such that all files with the same options and headers
       are arranged in groups and referenced through symbolic names 
      where possible. {\bf VisualMaker} reads your {\tt DCCOPTS} environment variable
      and shows them on the GUI. An option is included for setting this
      variable.   

      Header dependancies are obtained through scanning of the source files
      recursively, so even deeply nested subheaders are found. Every time a 
      headerfile is edited the dependant sources get recompiled. If the 
      precompile option is selected, precompiled headers will be deleted if 
      any of their dependancies are altered, thus causing {\bf DiCe} to precompile 
      anew. If compiler error output is redirected to a file, this errorfile
      will be deleted prior to every new compile run.
      
        Only headers included in double quotes (e.g. \verb- #include "defs.h"-) will
      be searched for (angle brackets should be reserved for system headers).
      Headers included inside of plain C comments (\verb# /*...*/ #) will be ignored,
      nested comments are not supported.

        The {\tt DMakefile} itself includes a list of dependancies and commands
      necessary for creating the executable, the object files, disassembled 
      files, automatic deletion of the Errorfile on startup, and for deletion 
      of objects and preprocessed files.



\section{Usage}

      Invoke {\bf VisualMaker} from the directory where you would like the 
      {\tt DMakefile} to be written to.  This is usually the directory 
      containing the brunch of your source files and from where the 
      compiler is started.

      The first thing {\bf VisualMaker} will do after invocation is to read 
      your {\tt DCCOPTS} environment variable, if found, and activate the 
      corresponding gadgets to reflect your default settings. 
      Choose all the files for your project with the {\bf {\sf GetFile}} Gadget in 
      the upper left corner (underneath the {\bf {\sf Generate}} Button). This will 
      bring up an ASL File\-Re\-quester. You can multiselect files by 
      simultaneously pressing the {\bf Shift} key. Alternatively you can use
      the {\bf {\sf A}} 
      Button (All) to choose all the files in your current directory in 
      one go. The files will show up in the {\bf {\sf Source List}} ListviewGadget. 
      (All files without a {\tt .c}, {\tt .a} or {\tt .o} extension will be filtered 
      out, as well as object files which have a corresponding source). 
      To remove files from the list, select them and press the {\bf {\sf R}} Button 
      (Remove). Now you can select your compiler options. The options are 
      divided into two classes, the global compiler options, which are 
      located underneath the {\bf {\sf Source List}} Listview gadget, apply to all 
      files in your project (e.g. Resident, Small/Large-Data model), and 
      the local compiler option, above the {\bf {\sf Source List}} ({\bf {\sf proto, --H, Stack, 
      NoProf}}). These may apply to only particular files (e.g. profiling of 
      only the time critical routines) as well as to all files. To turn on 
      local options select the files in question. To select a single file, 
      press the left mousebutton (LMB) over the file name. To select several
      files, drag the mouse while keeping the LMB pressed. To select 
      (or unselect) files which are momentarily not in the visible region, 
      drag the mouse over the rim of the gadget while keeping the button 
      pressed. Pressing a local option button now will effect the selected 
      files, showing the option behind the file name. For a comprehensive 
      explanation of the individual compiler options see the DiCe documentation 
      ({\tt dcc.doc}).

        The Program Name defaults to one of the source filenames in the
      Source List (minus the extension). The name can be easily changed to
      another source filname by selecting that particular file in the Source
      List, or of course by typing it into the string gadget.
        The {\bf {\sf Errorfile}} StringGadget specifies the output of compiler
      (Error)messages which is by default {\tt STDOUT}.
        The {\bf {\sf Output Dir}} StringGadget determines where the object files 
      are written to. If not specified they are written into the same 
      directory as the source files.
        The {\bf {\sf Temporary Dir}} StringGadget specifies the directory for 
      preprocessed files.
      
\pagebreak[4]
        To generate the {\tt DMakefile} press the {\bf {\sf Generate}} Button. All Files 
      will now be scanned, searching for any included headers in double 
      quotes (e.g. {\tt \#include "defs.h"}) and, if found, these will be scanned 
      as well, searching for subheaders and so on. Note: headers inside of 
      comments will not be searched. After the file has been written into 
      the current directory the program will exit.

        To leave the program without writing the {\tt DMakefile}, press the
      Close-Window gadget, or select {\bf {\sf Exit}} in the menu.

      


\section{Gadgets}   

\begin{description}

\item[CloseWindow] terminates the program {\it without} writing the {\tt DMakefile}.

\item[Generate]
  The {\tt DMakefile} will be written, and {\bf VisualMaker} will terminate.

\item[GetFile] 
      Pressing the {\bf {\sf GetFile}} Gadget brings up either a file- or directory
      requester. Some of the Requesters allow  multiselection  by holdding 
      down the {\bf Shift} key. After selection, files/directories will 
      be listed in the corresponding listview-gadget.
    
\item[Source List (ListviewGadget)]
      All Sourcefiles chosen with the File\-Re\-quester or {\bf {\sf A}} button 
      are listed. Any {\tt .o} or {\tt .a} files which also have a corresponding 
      {\tt .c} file will {\it not} be listed. When a particular file is selected 
      the local compiler options apply to this file. (De-)Selection is 
      simply done by pressing the nouse button over a particular source 
      name. Keeping the button pressed and dragging, allows multiselection.
      The name of the executable is automatically set to the last 
      selected file.

\item[R  (Remove)]
      Removes a selected File/Directory/Path from a Listview Gadget.

\item[A  (All)]
      This is a convenience button to select all files in the current 
      directory, bypassing the filerequester. Only files with a {\tt .c}, {\tt .a} 
      or {\tt .o} extension are selected and shown in the listviewgadget. If 
      a source and object file of the same name exist, only the source 
      file will be shown.

        e.g.  

\begin{quote}
\begin{tabbing}
\tt
spalteeinssssss\=arrow\=spaltezwei\kill
CURRENT DIR    \>               \>Source List\\
main.c main.o  \> $\rightarrow$ \> main.c\\
main.a main.o  \> $\rightarrow$ \> main.a\\
main.o         \> $\rightarrow$ \> main.o
\end{tabbing}
\end{quote}

      In other words, object files will only be shown if they are {\it extra 
      objects}.
      
\item[Program Name]
      Name of the executable program. If you select a filename from the
      Source List the extension will automatically be truncated and the
      rest placed into this string gadget. If this mechanism annoys you,
      just simpy type something into this Gadget manualy (a {\tt RETURN} will
      do) and the name will be {\it frozen}.
      
\item[Errorfile]
      Compiler error messages can be diverted to a particular file instead
      of {\tt STDOUT}. Useful if you have a means of proccessing these from your
      Editor with say an AREXX-script.
      
\item[Output Dir]
      The Directory where all object files ({\tt .o}) will be written to. If 
      not specified, each objectfile will be written into the same directory 
      its source resides in.

\item[Temporary Dir]
      The Directory where preprocessed files are written to.      

\end{description}

\section{Local Compiler Options}

\begin{description}
\item[--proto]
      Sets the {\tt -proto} compiler option, enabling prototype checking. All 
      functions not prototyped will cause an error during compilation. For 
      the amiga library functions, the corresponding \verb-*_protos.h- files in 
      the 'clib' direrctory have to be included. When compiling with 
      registered arguments ({\tt -mr/-mR/-mRR)} prototyping is mandatory.
      
\item[--H]
      Any header files referenced in the source file with \verb-#include "name.h"- 
      ({\bf Notice}: Header file in Quotes, {\it not} angle brackets) will be precompiled
      and placed into the temporary directory (Default: {\tt T:}) with 
      the name {\tt name.m}. This can speed up compilation time tremendously. 

        In the {\tt DMakefile} a dependancy will be created, deleting the 
      precompiled file whenever the corresponding headerfile or any subheaders 
      included in it are changed causing the compiler to generate a new 
      precompiled file. To precompile system headers e.g. \verb-<stdio.h>- or  
      \verb-<intuition/intuition.h>-, just include them in a header- or 
      subheaderfile, not in the source files or replace the angle brackets 
      with double quotes, but you'll probably have to add an absolute path.
      
\item[Stack/--mr/--mR/--mRR]
      Handling of function arguments.

\begin{description}
\item[Stack]   allows normal passing of function arguments via the stack.
\item[--mr]    cause the compiler to create both a stack and registered 
               argument entry point for functions.
\item[--mR]    cause the compiler to generate a single registered argument 
               entry point for each function.
\item[--mRR]   as above, but extends registration to indirect function 
               calls.
\end{description}
               The registered argument options switch on prototyping 
               automatically, as this is mandatory.


\item[NoProf / --prof1 / --prof2 / --prof3]
      En-/Disable profiling of either only the source ({\bf {\sf --prof1}}), source
      and clib functions ({\bf {\sf --prof2}}) or source, clib and amigalib functions
      ({\bf {\sf --prof3}}). With the latter two options, objects are linked 
      with the corresponding profiling libraries.

\end{description}      
   
\section{Global Compiler Options}

\begin{description}

\item[Resident]
      Sets the {\tt -r} compiler option, or if  {\bf {\sf No Reloc Hunk}} is enabled 
      the {\tt -pr} compiler option. This makes the code resident. 

\item[Dynamic Stack]
      Sets the {\tt -gs} compiler option, adding code for automatic stack 
      allocation if stack falls below a certain limit. (I have encountered
      some problems with this option).

\item[No Reloc Hunk]
      Sets either {\tt -pi}, or {\tt -pr} if {\bf {\sf Resident}} is also enabled, causing
      the compiler {\it not} to generate a relocation hunk.
                
\item[Small Data / Large Data]
      Sets the {\tt -md / -mD} compiler options to create either a small 
      (PC-relative) data model, or a large (absolute) data model.

\item[OS 2.0 / OS 3.0 / OS 1.3]
      Sets the {\tt -2.0 / -3.0 / -1.3} compiler options, telling the linker
      with which amiga library to link with.
      
\item[C${\tiny ++}$ Comments]
      Sets the {\tt -//} comiler option, letting the compiler recognize
      C${\tiny ++}$ style comments.

\item[Verbose]
      Sets the {\tt -v} compiler option which will show all {\tt dcc} commands
      in {\tt STDOUT} while executing.
        
\item[68000 / 68020 / 68030]
      Sets the {\tt -020 / -030} options, specifing the processor for which 
      the executable is written. (Default {\bf {\sf 68000}})
      
\item[Small Code / Large Code]
      Sets the {\tt -mc / -mC} compiler options for either small code
      (Default) or large code model.
      
\item[--ms0 / --ms1 / --ms2]
\begin{description}
\item[--ms0]   only {\tt const} data is put in code-hunk.
\item[--ms1]   string constants are also placed in code-hunk.
\item[--ms2]   as above, but all external {\tt const} references use near
              addressing.
\end{description}

\item[--unix]
      Objects are linked with the unix libraries.
      
\item[--chip]
      Force all hunks into chip memory.
      
\item[NoCoPro / --881 / --882]
      Tells the compiler to produce floatpoint code for corresponding
      co-processor.
      
\item[--lm]
      Objects are linked with the maths library for float\-point output 
      e.g. \verb-printf("%lf", ...)-. By default this is turned on whenever
      {\bf VisualMaker} encounters an \verb-"%*lf"- in the source code. See also
      the menu options.  

\item[--s]
      Add symbolic debugging information in the executable.

\item[--I0]
      Remove default include paths.
      
\item[--L0]
      Remove default library paths.

\end{description}
      
\section{The Backpanel}

    As you've probably noticed, you access this second panel of gadgets 
    by pressing the LMB anywhere inside the window outside of gadget
    activation areas. The top row of gadgets activates more esoteric
    options of the compiler and I will not go into these (see {\tt dcc.doc}).
      The listview gadgets underneath allow you to specify additional
    link libraries, library- and include paths. Their functionality is
    the same as with the {\bf {\sf Source List}}.
    
\begin{description}
\item[Link Library]
    You may specify additional libraries you want to link your code with.
    Only files with a {\tt ".lib"} extension are accessible through the library-
    requester. It is generally not necessary to add a particular model of 
    the standard c-, amiga-, or maths-library here since these are 
    automatically dealt with. 
      (e.g. {\tt muis.lib} - if you're working on a MUI project).
    
\item[Library Paths]
    Specify additional paths (directories) where the compiler should look
    for libraries if they are not located in the standard {\tt DLIB:} directory.
    
\item[Include Paths]
    Specify additional paths 
    where the compiler should look for include
    files not found in the standard {\tt DINCLUDE:} directory. The specified
    path will also be searched by {\bf VisualMaker} if it can't find one of your
    header files either in the current directory or the one the 
    corresponding source file is located in. 

\end{description}    
      
\section{The Menues}    
              
\begin{description}

\item[DCCOPTS]
    This will pop up a requester allowing you to save the currently set 
    compiler options in {\bf VisualMaker} to the {\tt DCCOPTS} environment variable.
    Three options are available:
\begin{description}
\item[SAVE]
        Options are saved permanently in {\tt ENVARC:DCCOPTS}.
\item[USE]
        Options are saved in {\tt ENV:DCCOPTS} and will be gone when computer 
        is turned off (provided your {\tt ENV:} directory is in {\tt ram:}).
\item[CANCEL]
        Self-explanatory.
\end{description}        

\item[check \%lf]
    This option causes {\bf VisualMaker} to search for any output of float-point 
    numbers in the source code and if found automatically set the {\tt "-lm"}
    option in the DMakefile which causes the compiler to link with math 
    library enabling output of {\tt float} and {\tt double} numbers (if not used
    float numbers are literally ouput as \verb-"<float>"-). The program does not 
    actually look for a 
\begin{quote}
\begin{verbatim}
                    '(s|f|v)printf("%...f")' 
\end{verbatim}
\end{quote}
    command but rather just the format string 
\begin{quote}
\begin{verbatim}

                   "%[0-9.l+-\*]*(E|e|f|F|g|G)",
\end{verbatim}
\end{quote}

    that is it does not know whether the expression is inside a printf-
    family type of command or just a simple string. The option is on by
    default but if it causes any problems due to the above mentioned,
    just turn it off (the {\tt -lm} option increases the executable size).

\item[EXIT]
    Leave program without writing the {\tt DMakefile}.        

\end{description}

        
\section{Using the DMakefile}

    {\tt DMake} can be called with several keywords, which determine what
    it does. These are:

\begin{description}

\item[{\tt {\bf DMake} all}]
\item[{\tt {\bf DMake} $<$executable$>$}]
        -generates the executable (Program Name), recompiling 
         everything that's necessary. The previous errofile (if specified 
         in {\bf VisualMaker}) is deleted prior to compilation. Note, if 
         a full pathname was specified for the executable in 
         {\bf VisualMaker} it should also be input here. This is case 
         sensitive.
        
\item[{\tt {\bf DMake} $<$file$>$.o}]
        -generates only the specified object file. Note, if an
         output directory was given this will have to be included,
         and is also case sensitive.
            e.g.  {\tt OUTDIR = dtmp: , OBJ = main.o \\
             $\Longrightarrow$ DMake dtmp:main.o}    and not  {\tt DTMP:main.o}
        
\item[{\tt {\bf DMake} $<$file$>$.a}]
        -generates only the specified disassembled file. The same
         applies as above.
                
\item[{\tt {\bf DMake} clean}]
        -deletes all object-, precompiled- and error- files.

\item[{\tt {\bf DMake} cleano}]
        -only deletes all objectfiles.

\end{description}


\section{Making Protos}

    If you want a dependancy for the automatic creation of a prototypes 
    file (e.g. {\tt protos.h}) then create an environment variable called 
    {\tt MAKEPROTO}. Place a string with your {\tt makeproto} calling format 
    followed by a blank and then the prototype filename.

\begin{description}
\item[Example1:]
        If you use Matt Dillon's {\tt makeproto} and your prototype file is
        called {\tt protos.h} use the following command:

\centerline{\verb+ Setenv MAKEPROTO "makeproto -o protos.h protos.h"+}
      

\item[Example2:]
        If you use Eric Smith's Public Domain {\tt mkproto} utility (my choice,
        since it extracts the prototypes directly out of the declared 
        functions) use the following command:

\centerline{\verb+ Setenv MAKEPROTO "mkproto >protos.h protos.h"+}
            
\end{description}
    To make this setting permanent copy {\tt env:MAKEPROTO} into the {\tt envarc:}
    directory.

\section{Timer Problems} 

    DMake uses the time-stamp of the files to determine whether a 
    recompilation is neccessary. If you do not have a clock, or it doesn't
    always function properly (mine sometimes sets itself back to {\tt Jan-78})
    in an unlucky case it could happen that a freshly edited dependent
    file has an older time stamp than its target file, causing {\tt DMake}
    not to resolve the dependency (and your bug-fix or added feature
    not showing up). 
\begin{quote}
       e.g. having the following dependancy,
       
       {\tt main.o : main.c\\
       \ \  dcc main.c -o main.o\\}
\end{quote}        
      say the target {\tt main.o} already exists from a previous session,
      in this session your timer misbehaves (setting itself back to the
      70's) and you edited {\tt main.c}, the new file won't be recompiled.

      The solution is either 

\begin{enumerate}
\item to always check and set the timer before starting a session, 
\item to manually set the date of {\tt main.c} with {\tt Date} or {\tt touch} 
      to something newer than {\tt main.o}, 
\item just simply by deleting the target {\tt main.o}.
\end{enumerate}


\section{Make Primer}      

      {\tt Make} is a utility program included in all serious compiler-packages 
      that automates the recompilation  process for large programs made up 
      of several  files.  When  making  changes to a particular file only 
      those files which are directly influenced by these changes (i.e. which 
      are dependant ) are recompiled, usually not all of them, which can 
      result in tremendous time savings as well as relieving the programer 
      from the burden of remembering and typing endless lines of compiler 
      commands.   
        {\tt Make} uses  the file  time-stamp in its considerations. The {\tt Make} 
      program is driven by a Makefile  which consists of a list of file 
      dependancies and command lines. Consider the following simple example:
      
\begin{quote}
        {\tt main.o : main.c\\
        \ \  dcc -c  main.c -o  main.o}
\end{quote}
      Here {\tt main.o} (target file) depends on {\tt main.c} (dependant file). If 
      the dependant file is newer than the target file or the target does 
      not exist, the dependancy is resolved, that is the command below is 
      executed. Several other forms of declaring dependancies are available. 
      Furthermore commands may be AmigaDOS commands such as {\tt Delete} etc. 
      For details of the syntax see the DMake manual.
      (A feature not documented is the prefixing of commands with a minus
      sign which will inhibit premature termination of {\tt DMake} if a command
      returns an error or warning). 
      
      Anyway, with {\bf VisualMaker} you should not have to worry about this!!
      Even if you are just compiling a single file, a DMakefile can still
      be of use. Your particular compiler options are saved and you don't
      have to worry about deleting the 'errorfile' (if redirected) prior
      to a new run (remember, the errors and warnings are always appended).
      
      An option I particularly recommend is the precompilation of header
      files. If you have enough memory, all headers, including the system
      headers (e.g. \verb- <intuition/intuition.h>-) may be precompiled. Since the
      compiler will then only have to read them {\it once} from your diskdrive,
      this saves a lot of time. To do this put all your definitions and 
      (system) include files in one header, say {\tt defs.h}, and reference 
      them with \verb-#include "defs.h"- from every source file which needs them.
\end{document}









